… 1 + event-outbox example

Two doc-only follow-ups surfaced by Phase 02a Packet 2 implementation:

- ADR-0023 Amendment 1 (2026-05-21): record the concrete Vogen 7.0.0 version
  pin (6.0.7 was no longer on NuGet when Directory.Packages.props was wired),
  and clarify that the `Aggregate_Roots_Use_StronglyTypedId` architecture
  test lands with the first concrete aggregate (Packet 6 — Tenancy) rather
  than Packet 2 (which has no aggregates yet — the test would be vacuous).
  Decision section untouched.

- architecture/15 example: `LocalizedMessage.Of("enrollment.created")` did
  not honour the `lockey_` prefix invariant Packet 2 just made canonical.
  Updated to `LocalizedMessage.Of("lockey_enrollment_created")` and the
  surrounding `Result.Success(...)` call switched to the canonical
  `Result<EnrollmentDto>.Ok(...)` factory.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Blocker fixes from the dual review of db230ae:

- Entity<TId> equality contract — transient entities (default Id) are now
  never equal to each other (only to themselves by reference), and a
  cross-runtime-type guard stops two distinct aggregate types that share
  the same Entity<TId> base + Id value from collapsing into the same
  change-tracker slot.
- Result.FailFor<TResponse> shape — was `<T> => Result<T>.Fail`, returning
  Result<Result<TValue>> whenever the pipeline behavior's TResponse is
  Result<TValue>. Now constrained `where TResponse : IResultBase` and
  reflection-driven so it returns the concrete TResponse the handler
  signature expects. Non-Result generic argument fails loud.

Major fixes:

- Error.Code is now the unprefixed stable identifier ("validation_failed")
  projected from Message.Key by stripping the lockey_ prefix; the wire
  Problem Details code stays in sync with Standards 04 § Problem Details
  AND the lockey_ invariant by construction. Error.Details typed as
  IReadOnlyDictionary<string, IReadOnlyList<LocalizedMessage>> so
  field-level messages cannot bypass the invariant.
- Result<T>.Ok throws on null value (Standards 09 § Forbidden); the
  primary constructor is now `internal` so positional record syntax cannot
  bypass the factory invariants. A new Unit value type covers the
  payload-less success shape.
- DomainEvent.EventId / OccurredAt are `required init` — the BCL-default
  initializers bypassed IGuidFactory / IClock, defeating the deterministic
  rule the abstractions exist for. Concrete events now stamp via
  injected abstractions at the call site.
- AuditableEntity actor columns (CreatedBy / UpdatedBy / DeletedBy) use a
  new strongly-typed UserId Vogen value object in SharedKernel.Identifiers
  rather than raw Guid; respects Standards 02 § Strongly-Typed Identifiers.
  The Identity module consumes the same UserId when it ships in 02b.
  ISoftDelete.DeletedBy stays Guid? at the marker layer (module-agnostic);
  AuditableEntity provides the Guid projection via explicit interface impl.
- AuditableEntity.MarkCreated throws on second call (audit-trail integrity).
  SoftDelete also bumps UpdatedAt / UpdatedBy so "last touched" is
  monotonic; the audit pipeline still categorises the delete via DeletedAt.
- CursorPagination ctor validates Limit > 0 (kernel-level guard); the
  API-layer FluentValidation is the place that translates malformed user
  input into Result.Fail. Normalised() no longer throws — only clamps.
- SharedKernel build-time-only references documented in csproj comments:
  EF Core (Vogen-emitted converter requires it) and MediatR (IDomainEvent :
  INotification). The standards-side exception lands in the follow-up
  docs commit.

Minors:

- Files split per Standards 02 § File Organization: IHasId, IAggregateRoot,
  IResultBase, Result static helper, Unit, LocalizedMessage all live in
  their own file. Entity<TId>.DomainEvents returns the backing list
  directly (no per-call AsReadOnly allocation).
- LocalizedMessage defensively copies Params at construction so caller
  mutations cannot leak in; structural equality (Key + Params) implemented
  explicitly so two messages built from the same source still compare
  equal. Empty params dictionary normalised to null. XSS contract
  documented (Params values must be plain text — frontend resolves via
  React text nodes, never dangerouslySetInnerHTML).
- ISoftDelete.IsDeleted DIM removed; AuditableEntity exposes IsDeleted
  directly so the contract is consistent per access path.
- FixedGuidFactory shared-queue contract documented in the XML doc.

Tests: 64 unit + 17 architecture + 1 contract green. New coverage for
transient + cross-type equality, FailFor<Result<T>>, Ok null guard,
MarkCreated second-call throw, CursorPagination ctor validation, and
LocalizedMessage defensive copy.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Records the corpus-side decisions that the code-side fixes (commit 7c9133a)
needed to land cleanly. Pure documentation; no code change.

- Standards 01 § Dependency Direction grows a "Build-time-only exceptions"
  sub-section spelling out the two sanctioned SharedKernel external
  references (Microsoft.EntityFrameworkCore via the Vogen-emitted
  EfCoreValueConverter, MediatR via IDomainEvent : INotification) with the
  ADR they trace to. Adding a third such reference now explicitly requires
  a new ADR. Names the follow-up architecture test that encodes the rule
  alongside the first Module.Domain aggregate in Packet 6.

- ADR-0023 Implementation Notes literal pin: the placeholder
  Version="..." is replaced with the concrete Version="7.0.0" already
  recorded in Amendment 1; the SharedKernel cross-cutting value-object list
  gains UserId; the EF Core transitive-reference rule is cross-linked to
  Standards 01.

- Standards 02 + 09 Result Type snippets reflect the refactored shape:
  internal primary constructor, Ok throws on null value, Error.Details
  typed as IReadOnlyDictionary<string, IReadOnlyList<LocalizedMessage>>,
  Error.Code projects from Message.Key by stripping the lockey_ prefix,
  Result<Unit> is the canonical payload-less success. The Standards 09
  error-code table prose is updated to the "table omits the prefix; wire
  format is the prefixed key, Code is the unprefixed stable identifier"
  shape that satisfies both Standards 04 § Problem Details and Standards
  09 § Forbidden.

- Glossary entries refreshed: Result<T> (internal ctor, Unit), Error
  (Code stripping, Details with LocalizedMessage lists), LocalizedMessage
  (structural equality, defensive copy, plain-text param contract),
  Entity / AuditableEntity (transient + cross-type equality guards,
  MarkCreated throws, SoftDelete bumps UpdatedAt), IDomainEvent
  (required init), CursorPagination (ctor guard); new UserId and Unit
  entries.

- Phase 02a Packet 2 status block records the review pass folded in,
  pointing to commit 7c9133a.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…e wiring + doc sync

All 13 findings from the third review pass (one APPROVE with 3 minor + 4
suggestion, one REQUEST CHANGES with 5 major + 2 minor + 1 suggestion)
verified against current code and applied.

Code (kernel) - majors:

- CursorPagination ctor now clamps `Limit > MaxLimit` to `MaxLimit`
  silently (still throws on `Limit <= 0` as a programmer-error guard).
  Removed `Normalised()` - the invariant is enforced at construction so
  no instance can exist with an out-of-range `Limit`. Drops the DoS
  footgun where a caller forgot to normalise and passed `int.MaxValue`
  into `.Take(...)`.
- Error switched to an explicit constructor: `ThrowIfNull(Message)` plus
  defensive snapshot of `Details` (dictionary copy + per-key
  `ReadOnlyCollection<LocalizedMessage>` wrap) so callers cannot mutate
  the validation map after the Result is in flight - Problem Details,
  audit, and log sinks all read after handler return. Structural Equals
  + GetHashCode override because `IReadOnlyDictionary` defaults to
  reference equality.
- UserId.New() removed - the convenience static was a tempting bypass of
  `IGuidFactory`. New UserIds in handlers now require
  `UserId.From(guidFactory.NewUuidV7())` at the call site.

Code (kernel) - minors:

- Entity<TId>.DomainEvents lazily allocates both the backing List<T> and
  the cached ReadOnlyCollection wrapper on first raise / first read. EF
  Core's read path materialises every loaded aggregate via the
  parameterless ctor; the lazy approach keeps materialisation
  allocation-free for the common query case (paginated reads,
  projections) and pays the allocation only when an aggregate actually
  raises events (command paths).
- LearnStackVogenDefaults moved from `LearnStack.SharedKernel.Identifiers`
  to the root `LearnStack.SharedKernel` namespace - the mask covers
  aggregate IDs AND richer value objects per ADR-0023, so neither
  surface owns the constant exclusively. The Vogen attribute on UserId
  / TestId still resolves it via parent-namespace lookup; TestId in the
  test project gains an explicit `using LearnStack.SharedKernel;`.
- AuditableEntity.IsDeleted XML doc is now honest about EF translation:
  the property is a computed CLR get and is NOT guaranteed to translate
  by EF Core's expression translator. Global query filters in Packet 7
  should gate on `e.DeletedAt == null` directly (the mapped column
  translates cleanly).

Tests:

- CursorPaginationTests rewritten: ctor clamp, boundary cases
  (Limit == MaxLimit, Limit == 1), removed all `Normalised()` references.
- ErrorTests: ctor null-Message throw, defensive-copy assertion (caller
  mutates the source dictionary + list after construction; the Error's
  Details remain stable), structural-equality across distinct dictionary
  instances.
- FixedGuidFactoryTests: mixed V7+V4 seed test locks the documented
  shared-queue contract.
- Total: 77 unit (+6 since previous round) + 17 architecture + 1
  contract green under CI=true.

Module wiring (B.M5):

- New `backend/src/Modules/Directory.Build.props` adds the Vogen +
  Microsoft.EntityFrameworkCore PackageReferences to every
  `Modules.<X>.Domain` project via `EndsWith('.Domain')` condition.
  Explicitly imports the parent `backend/Directory.Build.props` because
  MSBuild stops at the first ancestor Directory.Build.props it finds
  rather than merging up. This closes the gap ADR-0023 § Implementation
  Notes promised but the original Packet 2 land did not deliver:
  `[ValueObject<Guid>(LearnStackVogenDefaults.IdMask)]` on a
  TenantId / CourseId / OrganizationId etc. in Packet 6+ will now
  "just work" without per-csproj wiring.

Docs:

- Standards 02 § Strongly-Typed Identifiers snippet rewritten to the
  canonical Vogen form (the stale hand-rolled example with
  `Guid.NewGuid()` was misleading new module authors). Adds the
  no-`New()` rule: IDs mint via `IGuidFactory` at the call site.
- Standards 09 § API Surface example refreshed: top-level uses
  `messageKey` (`lockey_*`) and `code` (unprefixed stable id); field
  errors flow as LocalizedMessage payloads (`key` + optional `params`)
  so the lockey_ invariant covers the entire wire shape, not just the
  top-level message.
- architecture/15 handler example: `OccurredAt = _clock.UtcNow` instead
  of `DateTime.UtcNow` (closes the symmetric `IClock`-bypass anti-
  example the reviewer caught).
- Phase 02a Packet 2 roadmap status: test counts refreshed (54 / 64 →
  71 — actually now 77 after this round); TypeConverter coverage noted.

Suggestion not adopted:

- IRandom rename / NextBytes removal — deferred to the Packet 3+
  analyzer pass (both reviewers raised it as a future-analyzer
  concern). The XML doc already warns "not for crypto"; an analyzer
  banning IRandom in *.Security.* / *.Auth.* namespaces is the right
  enforcement surface and lands with the Roslyn analyzer infrastructure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>